%  Copyright (C) 2002 Regents of the University of Michigan, portions used with permission 
%  For more information, see http://csem.engin.umich.edu/tools/swmf
%\documentclass{article}
%\begin{document}

\section{PARAM.in \label{section:param.in}}

The input parameters for the \BATSRUS\ code are read from the 
{\tt PARAM.in} file which must be located in the run directory.
The file controls all of the \BATSRUS\ functionality.
When \BATSRUS\ runs as part of the SWMF, the parameters for 
the component represented by \BATSRUS\ (for example GM) are
given between the 
\begin{verbatim}
#BEGIN_COMP GM
...
#END_COMP GM
\end{verbatim}
commands. We refer to the lines starting with a \# character as commands.

There are several features of the input parameter file syntax
that allow the user to easily run the code
in a variety of modes while at the same time being able to 
keep a library of useful parameter files that can be used
again and again.

The user should be aware of and become intimately attached to the 
{\bf {\tt PARAM.XML}} file located in the main \BATSRUS\ directory.  
This file contains the most detailed 
description and complete list of the all the input parameters
used by \BATSRUS. The same file is used to produce much of this
manual with the aid of the share/Scripts/XmlToTex.pl script. 
The {\tt TestParam.pl} script also uses the {\tt PARAM.XML} file
to check the PARAM.in file.
Copying small segments of the {\tt PARAM.XML} file
into {\tt PARAM.in} can speed up the creation or modification of a 
parameter file. 

If the command string 
\begin{verbatim}
#END
\end{verbatim}
is present, it indicates the end of the run and lines following
this command are ignored. If the \#END command is not
present, the end of the file indicates the end of the run.

\section{Included Files, {\tt \#INCLUDE} \label{section:include}}

The {\tt PARAM.in} file can include other parameter files with the 
command
\begin{verbatim}
#INCLUDE
include_parameter_filename
\end{verbatim}
The include files serve two purposes: (i) they help
to group the parameters; (ii) the included files can be reused
for other parameter files. 
An include file can include another file itself.
Up to 10 include files can be nested.
The include files have exactly the same structure as {\tt PARAM.in}. 
The only difference is that the
\begin{verbatim}
#END
\end{verbatim}
command in an included file means only the end of the include file, 
and not the end of the run, as it does in {\tt PARAM.in}.

The user can place his/her
included parameter files into the main run directory or in any subdirectory
as long as the correct path to the file from the run directory is
included in the {\tt \#INCLUDE} command.
There are many include files in the {\tt Param} directory. These
can be included into the {\tt PARAM.in} files, or they can serve as
examples. 

\section{Commands, Parameters, and Comments \label{section:commands}}

As can be seen from the above examples,  parameters are entered
with a combination of a {\bf command} followed by specific {\bf parameter(s)},
if any.
The {\bf command} must start with a hashmark (\#), which 
is followed by capital letters and underscores without space in between. 
Any characters behind the first space or TAB character are ignored
(the \#BEGIN\_COMP and \#END\_COMP commands are the only exception,
but these are markers rather than commands).
The parameters, which follow, must conform to 
requirements of the command. They can be of four types: logical, integer,
real, or character string. Logical parameters can be entered as 
{\tt .true.} or {\tt .false.} or simply {\tt T} or {\tt F}.
Integers and reals can be in any of the usual Fortran formats.
All these can be followed by arbitrary comments, typically separated
by space or TAB characters. In case of the character type input
parameters (which may contain spaces themselves), the comments must
be separated by a TAB or by at least 3 consecutive space characters.
Comments can be freely put anywhere between two commands as long
as they don't start with a hashmark.

Here are some examples of valid commands, parameters, and comments:
\begin{verbatim}

#TIMEACCURATE
F                       DoTimeAccurate

Here is a comment between two commands...

#INNERBOUNDARY
ionosphereB0            TypeBcInner (3 spaces or TAB before the comment)

#STOP
-1.                     tSimulationMax
100		        MaxIteration

#RUN ------------ last command of this session -----------------

#BORIS
T                       UseBorisCorrection
0.10                    BorisClightFactor

\end{verbatim}
Note that in the SWMF some of these commands would be in the
part of the PARAM.in file which is intended for the control 
module CON, while the ones specific to \BATSRUS\ (e.g. the
\#INNERBOUNDARY and \#BORIS commands would be enclosed
between the \#BGIN\_COMP and \#END\_COMP markers.
In the detailed description of all commands, 
it is explicitly stated if a command can only be used in 
the stand alone mode.

\section{Sessions \label{section:sessions}}

A single parameter file can control consecutive {\bf sessions}
of the run. Each session looks like
\begin{verbatim}
#SOME_COMMAND
param1
param2

...

#STOP
max_simulation_time_for_this_session
max_iter_for_this_session

#RUN
\end{verbatim}
while the final session ends like
\begin{verbatim}
#STOP
max_simulation_time_for_final_session
max_iter_for_final_session

#END
\end{verbatim}
The purpose of using multiple sessions is to be able to change parameters 
during the run. For example one can obtain a coarse steady state solution
with a low order scheme in the first session, improve on the solution
with a better scheme and finer grid in the second session, then switch
to time accurate mode in the third session. The code remembers parameter
settings from all previous sessions, so in each session one should only
set those parameters which change relative to the previous session.
Note that the maximum number of iterations given in the {\tt \#STOP} command 
is meant for the entire run, and not for the individual sessions. 
On the other hand, when a restart file is read, the iterations prior to 
the current run do not count.

The {\tt PARAM.in} file and all included parameter files are read into 
a buffer 
at the beginning of the run, so even for multi-session runs, changes in
the parameter files have no effect once {\tt PARAM.in} has been read.

\section{The Order of Commands \label{section:order}}

In essence, the order of parameter commands ({\tt \#COMMAND}) is arbitrary, 
but there are some important restrictions.  We should note that the 
order of the parameters following the command are not however arbitrary 
and must exactly match what the code requires.  

If you want all the input parameters to be echoed back, the first
command in {\tt PARAM.in} should be
\begin{verbatim}
#ECHO
T                 DoEcho
\end{verbatim}
If the run starts from scrath (not restarted) the next commands should be
\begin{verbatim}
#PROBLEMTYPE
problem_type_number
\end{verbatim}
and 
\begin{verbatim}
#GRID
...
\end{verbatim}
The problem type sets the default values for many parameters,
which may be overwritten by the following commands. If the 
problem type was set later it could overwrite the previous
settings with the default values!
The grid command sets the size of the computational domain,
which is used in the \#SAVEPLOT command, for example.
The rest of the commands can be in arbitrary order.

If the code starts from restart files, it reads in the
{\tt \#PROBLEMTYPE} and {\tt \#GRID} commands from the 
restart header file.
This should be done with an \#INCLUDE command, which
should be at the beginning of the PARAM.in file. For example
\begin{verbatim}
#INCLUDE
GM/restartIN/restart.H
\end{verbatim}
In older versions of \BATSRUS, the same effect was achieved 
with the \#RESTART command. For sake of backwards compatibility
the \#RESTART command is still supported in
the stand alone mode as long as the input restart directory
is the default one. It is recommended, however, to use
the \#INCLUDE command instead, because it does not have
to be changed when a stand alone PARAM.in file is used
in an SWMF input file, and it also allows to use a non-default
directory name.

There are several parameters which should not be changed once the code 
has begun to execute.  
In other words, these parameters can be defined only during the first
session.  These parameters typically either involve geometries which 
cannot be changed, or physical parameters for which there is no reasonable 
reason to change. These commands are marked with an 
{\tt if=''\$\_IsFirstSession''} conditional in the PARAM.XML file.
Some of the more commonly used first-session-only commands are
\begin{verbatim}
#PROBLEMTYPE 
#GRID 
#AMRINIT
#GAMMA
#SOLARWIND
#MAGNETOSPHERE
#BODY
#SECONDBODY
\end{verbatim}
If any of these parameters are attempted to be changed in later sessions, 
a warning is printed on the screen, and the command is ignored.

In several commands the frequency or 'time' of some action has
to be defined. This is usually done with a pair of parameters.
The first defines the frequency or time in terms of the number of time steps,
and the second one in terms of the simulation time.
A negative value for the frequency means that it should not be taken 
into account. For example, in time accurate mode,
\begin{verbatim}
#SAVERESTART
T            DoSaveRestart
2000         DnSaveRestart
-1.          DtSaveRestart
\end{verbatim}
means that a restart file should be saved after every 2000th time step, while
\begin{verbatim}
#SAVERESTART
T            DoSaveRestart
-1           DnSaveRestart
100.0        DtSaveRestart
\end{verbatim}
means that it should be saved every 100 second in terms of physical time.
Defining positive values for both frequencies might be useful
when switching from steady state mode to time accurate mode.
In the steady state mode the DnSaveRestart parameter is used,
while in time accurate mode the DtSaveRestart if it is positive.
But it is more typical and more intuitive to either 
use the frequencies based on time steps in all sessions, 
or to explicitly repeat the command in the first 
time accurate session with the time frequency set.

\section{Command Defaults \label{section:defaults}}

A quick glance the the {\tt PARAM.XML} file shows that there is an 
overwhelmingly large number of input parameters to \BATSRUS.  
Especially daunting is the long
list of parameters which controls details of the numerical methods that the
code uses.  Fortunately, many of these will never need to be set by the 
beginning user.  

\BATSRUS\ sets many of the parameters to reasonable values in the source file 
{\tt MH\_set\_parameters.f90}.  The two routines
{\tt set\_defaults} and {\tt set\_problem\_defaults} set 
the appropriate values.
The defaults have been chosen because they work for the vast
majority of problems for which the code has been run.  
The {\tt PARAM.XML} file defines which commands are required
with the {\tt required=''T''} attribute of the {\tt <command...>} tag.
In general, commands which deal with details of numerics are defaulted to 
reasonable values.
These may (and should) need to be changed eventually by most users 
to achieve the desired code speed or solution accuracy, but will
work reasonably well with the defaults for most problems.
Physics parameters are also defaulted by the problem type and should work fine
when running the code on a previously run problem.  
This will be commonly changed by users as they begin to run their 
own simulations. Finally, geometry, problem type,
flow control (time stepping, start and stops, etc.) and plotting output 
are generally not defaulted.

\section{Iterations and Frequency of Output \label{section:frequency}}

The purpose of this section is to try to help the user understand what at
first may seem like an inconsistent use of stopping frequencies and output
frequencies.  After using \BATSRUS\ over several years, it is clear to the
authors that the code is used in specific ways and the frequencies are
very specifically designed to meet these needs and is the 
most reasonable implementation. The main ``inconsistencies''
come into play when the code is restarted, but let us begin by 
elaborating on time stepping and output frequencies in the code.

We begin by defining several different quantities and the variables that 
represent them in the code.  The variable {\tt nITER}, represents the number
of ``iterations'' that the simulation has taken since it began running.  
This number starts at zero every time the code is run, even if beginning 
from a restart file.
This is reasonable since most users know how many iterations the code can take
in a certain amount of CPU time and it is this number that is needed when 
running in a queue.
The quantity {\tt n\_step} is a number of ``time steps'' that the code has 
taken in total.  This number starts at zero when the code is started from 
scratch, but when started from a restart file, this
number will start with the time step at which the restart file was written.
This implementation lets the user output data files at a regular interval, even
when a restart happens at an odd number of iterations.
The quantity {\tt time\_simulation} is the amount of simulated, or physical, 
time that the code has run.  
This time starts when time accurate time stepping begins.
When restarting, it starts from the physical time for the restart.
Of course the time should be cumulative since it is the physically meaningful
quantity.  We will 
use these three phrases( ``iteration'', ``time step'', ``time'') 
with the meanings outlined above.

As outlined in section~\ref{section:order}, commands that ask for a 
frequency of doing something (say 
writing the restart file) or for ending a session asks for either a number of
iterations, time steps or a physical (simulated) time, depending on 
whether the time
stepping mode is local or time accurate.
With the {\tt \#SAVERESTART} command, for example, in local time stepping mode
the command with its parameters would be
\begin{verbatim}
#SAVERESTART
T            DoSaveRestart
2000         DnSaveRestart
-1.          DtSaveRestart
\end{verbatim}
and a restart file would be written to disk every 2000 time steps. 
A negative value for the time frequency means that it should not be taken 
into account. The previous command works in time accurate mode too, 
but it ismore typical to define the frequency in physical time:
\begin{verbatim}
#SAVERESTART
T            DoSaveRestart
-1           DnSaveRestart
100.0        DtSaveRestart
\end{verbatim}
which means that the restart files should be saved every 100 seconds. 
Defining positive values for both frequencies is possible but not
very easy to read. In steady state mode the time step frequency, 
while in time accurate mode the physical time frequency will be used.

Now, what happens when the user has more than one session and he or she
changes the frequencies.  Let us examine what would happen in the following
sample of part of a {\tt PARAM.in} file.  For the following example we will
assume that when in time accurate mode, 1 iteration simulates 1 second of time.
Columns to the right indicate the values of {\tt nITER}, {\tt n\_step} and
{\tt time\_simulation} at which restart files will be written in each session.

\clearpage

\begin{alltt}
                                             Restart Files Written at:
==SESSION 1       \hfill        Session   nITER   n_step   time_simulation
#TIMEACCURATE	  \hfill        --------  ------  -------  --------------
F            DoTimeAccurate  

#SAVERESTART                      \hfill  1       200      200              0.0  
T            DoSaveRestart     \hfill  1       400      400              0.0
200          DnSaveRestart
-1.0         DtSaveRestart

#STOP
400          MaxIteration
-1.          tSimulationMax

#RUN ==END OF SESSION 1== 
                         
#SAVERESTART			  \hfill  2       600      600              0.0
T            DoSaveRestart	  \hfill  2       900      900              0.0
300          DnSaveRestart
-1.0         DtSaveRestart
				
#STOP				
1000         MaxIteration				
-1.          tSimulationMax
				
#RUN ==END OF SESSION 2== 

#TIMEACCURATE
T            DoTimeAccurate  		
				
#SAVERESTART			  \hfill  3      1100     1100            100.0
T            DoSaveRestart	  \hfill  3      1200     1200            200.0
-1           DnSaveRestart  \hfill  3      1300     1300            300.0
100.0        DtSaveRestart
				
#STOP				
-1           MaxIteration				
300.0        tSimulationMax			
				
#RUN ==END OF SESSION 3== 
                          
#SAVERESTART                \hfill   4      1400     1400            400.0
T            DoSaveRestart  \hfill   4      1800     1800            800.0
-1           DnSaveRestart  \hfill   4      2000     2000           1000.0
400.0        DtSaveRestart
 				
#STOP				
-1           MaxIteration				
1000.0       tSimulationMax				
				
#END  ==END OF SESSION 4== 
\end{alltt}
Now the question is how many iterations will be taken and when will restart
file be written out.  In session 1 the code will make 400 iterations and will
write a restart file at time steps 200 and 400.  Since the iterations 
in the {\tt \#STOP}
command are cumulative, the {\tt \#STOP} command in the second session will
have the code make 600 more iterations for a total of 1000.  Since the timing
of output is also cumulative, a restart file will be written at time step 600
and at 900.
After session 2, the code is switched to time accurate mode.  Since we
have not run in this mode yet the simulated (or physical) time is cumulatively
0.  The third session will run for 300.0 simulated seconds (which for the
sake of this example is 300 iterations).  The restart file will be written
after every 100.0 simulated seconds or in other words at time steps
1100, 1200 and 1300.
The {\tt \#STOP} command in Session 4  tells the code to simulate  700.0 more 
seconds for a total of 1000.0 seconds.  The code will make a restart file
when the time is a multiple of 400.0 seconds or at 400.0 and 800.0 seconds (1400 and
1800 time steps).  Note that a restart file will also be written at time 1000.0
seconds
(time step 2000) since this is the end of a run.

Hopefully it is clear how the simulation is stopped and when output is written.
Unfortunately, when restarting, things change just slightly. 
Let us say that we want to restart running from where our previous example left off.
We had written a final restart file at 1000.0 seconds of simulated time, which
was 2000 time steps.  We want to have the following {\tt PARAM.in} file
executed. 
\begin{alltt}
                                             Restart Files Written at:
==SESSION 1      \hfill        Session   nITER   n_step   time_simulation
                 \hfill        --------  ------  -------  --------------
#INCLUDE                         \hfill            0     2000           1000.0
GM/restartIN/restart.H

#TIMEACCURATE
F            DoTimeAccurate  

#SAVERESTART                      \hfill  1       200     2200           1000.0
T            DoSaveRestart
1100         DnSaveRestart
-1.0         DtSaveRestart

#STOP
500          MaxIteration
-1.          tSimulationMax

#RUN ==END OF SESSION 1== 

#SAVERESTART                      \hfill  2       700     2700           1000.0
T            DoSaveRestart	  \hfill  2      1000     3000           1000.0
300          DnSaveRestart
-1.0         DtSaveRestart

#STOP
1000         MaxIteration
-1.          tSimulationMax

#END ==END OF SESSION 2== 
                          
\end{alltt}
Since we switched to local time stepping we only have to worry about iteration
number and time steps.  Here we notice the difference in the {\tt \#STOP} command when
restarting and looking at the iteration number.  With a restart, 
the {\tt \#STOP} command does not consider the cumulative number of time steps but starts
again.  However, the output frequency is based on the cumulative time step.  
The simulation will make 500 iterations
in the first session.  This would cumulatively be 2500 time steps.  The restart
file will be written out at 2200 cumulative time steps or at 200 iterations into this
session.  The second session will make 500 more iterations for a total of 1000
in this run or 3000 time steps over all.  A restart file will be written out at multiples
of 300 time steps taken relative to the cumulative total number of time steps.  In other
words at 2700 and 3000 time steps over all, which is at 700 and 1000 iterations in
this run.

This example shows how iterations for stopping are cumulative within a run but
are not at restart, but that output is always based on the cumulative number of time steps.

Now let us take one last example.  We want to restart from 1000.0 seconds (2000 time steps)
just as in the previous example, but we want to continue with a time accurate run.
\begin{alltt}
                                             Restart Files Written at:
==SESSION 1      \hfill        Session   nITER   n_step   time_simulation
                 \hfill        --------  ------  -------  --------------
#INCLUDE                         \hfill            0     2000           1000.0
GM/restartOUT/restart.H

#TIMEACCURATE
T            DoTimeAccurate  

#SAVERESTART                      \hfill  1       200     2200           1200.0
T            DoSaveRestart
-1           DnSaveRestart
600.0        DtSaveRestart

#STOP
-1           MaxIteration
1500.0       tSimulationMax

#RUN ==END OF SESSION 1== 

#SAVERESTART                      \hfill  2       700     2700           1500.0
T            DoSaveRestart	  \hfill  2      1000     3000           2000.0
-1           DnSaveRestart
750.0        DtSaveRestart

#STOP
-1           MaxIteration
2000.0       tSimulationMax

#END ==END OF SESSION 2 = 
                          
\end{alltt}
In this example, we see that in time accurate mode the simulated, or
physical, time is always cumulative.  To make 500.0 seconds more simulation,
the original 1000.0 seconds must be taken into account.  In this example,
since each second is 1 iteration, the restart file would be written at the
same time steps as in the previous example.  The final output (at 2000.0 seconds)
in this case
is not because a frequency was hit but because
the run ended.

Throughout this section, we have used the frequency of writing restart files
as an example.  The frequencies of writing plot files, writing logfiles and
doing AMR work similarly.
When some of these files are written, they have in the file name a time step
number.  This number is always the cumulative number of time steps.

%\end{document}
